{ "openapi": "3.0.0", "info": { "title": "Giftcard Hub API", "description": ">ℹ️ Check the new [Payments onboarding guide](https:\/\/developers.vtex.com\/vtex-rest-api\/docs\/payments-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Payments and is organized by focusing on the developer's journey.\r\n\r\nThe Gift Card Hub API allows interactions with all Gift card providers registered to a store from a single point.\r\n\r\nGift card providers are systems capable of providing cards to be used in the buying process.\r\n\r\nThe following is the sequence diagram that represents calls in the purchase closing process.\r\n![](https:\/\/cdn.jsdelivr.net\/gh\/vtexdocs\/dev-portal-content@main\/images\/gift-card-integration-guide-provider-protocol-0.png)\r\n\r\n**Checkout + Gateway**: Systems responsible for the sale and for processing orders and payments.\r\n\r\n**Gift Card Hub**: System responsible for managing multiple registered Gift card providers for a store.\r\n\r\n**Gift Card Provider**: System responsible for providing the Gift cards available to the user not closing a purchase. This system can be implemented by third parties.\r\n\r\n## Gift card Hub API Index\r\n\r\n### Provider\r\n\r\n- `PUT` [Create or update a gift card provider by ID](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-hub-api#put-\/api\/giftcardproviders\/-giftCardProviderId-)\r\n- `GET` [Get a gift card provider by ID](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-hub-api#get-\/api\/giftcardproviders\/-giftCardProviderId-)\r\n- `GET` [List all gift card providers](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-hub-api#get-\/api\/giftcardproviders)\r\n- `DELETE` [Delete a gift card provider by ID](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-hub-api#delete-\/api\/giftcardproviders\/-giftCardProviderId-)\r\n\r\n### Transaction\r\n\r\n- `POST` [Create a gift card at a gift card provider](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-hub-api#post-\/api\/giftcardproviders\/-giftCardProviderId-\/giftcards)\r\n- `POST` [Get a gift card from a gift card provider](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-hub-api#post-\/api\/giftcardproviders\/-giftCardProviderId-\/giftcards\/_search)\r\n- `GET` [Get a gift card from a gift card provider by ID](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-hub-api#get-\/api\/giftcardproviders\/-giftCardProviderId-\/giftcards\/-giftCardId-)\r\n- `POST` [Create a gift card transaction](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-hub-api#post-\/api\/giftcardproviders\/-giftCardProviderId-\/giftcards\/-giftCardId-\/transactions)\r\n- `GET` [Get a gift card transaction by ID](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-hub-api#get-\/api\/giftcardproviders\/-giftCardProviderId-\/giftcards\/-giftCardId-\/transactions\/-transactionId-)\r\n- `GET` [List all gift card transactions](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-hub-api#get-\/api\/giftcardproviders\/-giftCardProviderId-\/giftcards\/-giftCardId-\/transactions)\r\n- `GET` [Get a gift card transaction authorization](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-hub-api#get-\/api\/giftcardproviders\/-giftCardProviderId-\/giftcards\/-giftCardId-\/transactions\/-tId-\/authorization)\r\n- `POST` [Cancel a gift card transaction](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-hub-api#post-\/api\/giftcardproviders\/-giftCardProviderId-\/giftcards\/-giftCardId-\/transactions\/-tId-\/cancellations)\r\n- `GET` [List all gift card transactions cancellations](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-hub-api#get-\/api\/giftcardproviders\/-giftCardProviderId-\/giftcards\/-giftCardId-\/transactions\/-tId-\/cancellations)\r\n- `POST` [Settle a gift card transaction](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-hub-api#post-\/api\/giftcardproviders\/-giftCardProviderId-\/giftcards\/-giftCardId-\/transactions\/-tId-\/settlements)\r\n- `GET` [List all gift card transactions settlements](https:\/\/developers.vtex.com\/docs\/api-reference\/giftcard-hub-api#get-\/api\/giftcardproviders\/-giftCardProviderId-\/giftcards\/-giftCardId-\/transactions\/-tId-\/settlements)", "contact": {}, "version": "1.0" }, "servers": [ { "url": "https://{accountName}.{environment}.com.br", "description": "VTEX server URL.", "variables": { "accountName": { "description": "Name of the VTEX account. Used as part of the URL.", "default": "apiexamples" }, "environment": { "description": "Environment to use. Used as part of the URL.", "enum": [ "vtexcommercestable" ], "default": "vtexcommercestable" } } } ], "paths": { "/api/giftcardproviders": { "get": { "tags": [ "Provider" ], "summary": "List all gift card providers", "description": "Returns a collection of gift card providers from a store.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **View Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "ListAllGiftCardProviders", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "REST-Range", "in": "header", "description": "Pagination control. This query variable must follow the format `_resources={from}-{to}_`.", "required": false, "style": "simple", "schema": { "type": "string", "default": "resources=0-49" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "Gift card providers information.", "properties": { "id": { "type": "string", "description": "Gift card provider identification." }, "serviceUrl": { "type": "string", "description": "URL from the provider." }, "oauthProvider": { "type": "string", "description": "Provider's authentication." }, "preAuthEnabled": { "type": "boolean", "description": "Related to the pre-authorization that can happen on the transaction generated through the provider." }, "cancelEnabled": { "type": "boolean", "description": "Indicates whether it is possible to cancel the transaction, generated through the provider." }, "_self": { "type": "object", "description": "Object that carries an auto reference from the provider at the Hub (on its API).", "properties": { "href": { "type": "string", "description": "This is one of the fields inside the `_self`. It is exactly the route that identifies this provider on the Hub's API, but it is not the same thing as the `serviceURL`." } } } } } }, "example": [ { "id": "GiftCardExample", "serviceUrl": "https://api.vtex.com.br/basedevmkp", "oauthProvider": "vtex", "preAuthEnabled": true, "cancelEnabled": true, "_self": { "href": "cosmet/giftcardproviders/GiftCardExample" } }, { "id": "GiftCardExample2", "serviceUrl": "https://giftcard--cosmetics2.myvtex.com/my-provider", "oauthProvider": "vtex", "caption": "My Updated Gift Card Provider", "preAuthEnabled": true, "cancelEnabled": true, "_self": { "href": "cosmet/giftcardproviders/GiftCardExample2" } } ] } } } } } }, "/api/giftcardproviders/{giftCardProviderId}": { "get": { "tags": [ "Provider" ], "summary": "Get a gift card provider by ID", "description": "Returns a gift card provider from a store.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **View Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "GetGiftCardProviderbyID", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Gift card provider identification." }, "serviceUrl": { "type": "string", "description": "URL from the provider." }, "oauthProvider": { "type": "string", "description": "Provider's authentication." }, "caption": { "type": "string", "description": "Description about the provider." }, "preAuthEnabled": { "type": "boolean", "description": "Related to the pre-authorization that can happen on the transaction generated through the provider." }, "cancelEnabled": { "type": "boolean", "description": "Indicates whether it is possible to cancel the transaction, generated through the provider." }, "_self": { "type": "object", "description": "Object that carries an auto reference from the provider at the Hub (on its API).", "items": { "type": "object", "description": "Provider route information.", "properties": { "href": { "type": "string", "description": "This is one of the fields inside the `_self`. It is exactly the route that identifies this provider on the Hub's API, but it is not the same thing as the `serviceURL`." } } } } } }, "example": { "id": "GiftCardExample", "serviceUrl": "https://api.vtex.com.br/basedevmkp", "oauthProvider": "vtex", "caption": "My Updated Gift Card Provider", "preAuthEnabled": true, "cancelEnabled": true, "_self": { "href": "cosmet/giftcardproviders/GiftCardExample" } } } } }, "500": { "description": "Object reference not set to an instance of an object (The gift card provider described does not exist)." } } }, "put": { "tags": [ "Provider" ], "summary": "Create or update a gift card provider by ID", "description": "Create or update a gift card provider from a store.\r\n\r\n> ⚠️ The `appkey` and `apptoken` fields are not mandatory for the native VTEX gift card, only for external gift card providers.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Edit Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "Create/UpdateGiftCardProviderbyID", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "customProvider" } } ], "requestBody": { "content": { "application/vnd.vtex.giftcardproviders.v1+json": { "schema": { "$ref": "#/components/schemas/CreateUpdateGiftCardProviderbyIDRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Gift card provider identification." }, "serviceUrl": { "type": "string", "description": "URL from the provider." }, "oauthProvider": { "type": "string", "description": "Provider's authentication." }, "preAuthEnabled": { "type": "boolean", "description": "Related to the pre-authorization that can happen on the transaction generated through the provider." }, "cancelEnabled": { "type": "boolean", "description": "Indicates whether it is possible to cancel the transaction, generated through the provider." }, "_self": { "type": "object", "description": "Object that carries an auto reference from the provider at the Hub (on its API).", "items": { "type": "object", "description": "Provider route information.", "properties": { "href": { "type": "string", "description": "This is one of the fields inside the `_self`. It is exactly the route that identifies this provider on the Hub's API, but it is not the same thing as the `serviceURL`." } } } } } }, "example": { "id": "customProvider", "serviceUrl": "https://api.vtex.com.br/basedevmkp", "oauthProvider": "vtex", "preAuthEnabled": true, "cancelEnabled": true, "_self": { "href": "cosmetics2/giftcardproviders/customprovider" } } } } } } }, "delete": { "tags": [ "Provider" ], "summary": "Delete a gift card provider by ID", "description": "Delete a gift card provider from a store.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Edit Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "DeleteGiftCardProviderbyID", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } } ], "responses": { "200": { "description": "OK. This endpoint does not return any data in the response body." }, "404": { "description": "Not Found" } } } }, "/api/giftcardproviders/{giftCardProviderId}/giftcards": { "post": { "tags": [ "Transaction" ], "summary": "Create a gift card at a gift card provider", "description": "Creates a gift card in a gift card provider.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Edit Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "CreateGiftCardinGiftCardProvider", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } } ], "requestBody": { "content": { "application/vnd.vtex.giftcardproviders.v1+json": { "schema": { "$ref": "#/components/schemas/CreateGiftCardinGiftCardProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Gift card identification." }, "emissionDate": { "type": "string", "description": "Gift card emission date." }, "expiringDate": { "type": "string", "description": "Gift card expiration date." }, "caption": { "type": "string", "description": "Field to be filled in if a loyalty program must be created for the gift card." }, "provider": { "type": "string", "description": "Provider name." }, "discount": { "type": "boolean", "description": "Deprecated field.", "deprecated" : true }, "currencyCode": { "type": "string", "description": "Currency code in ISO 4217." }, "transaction": { "type": "object", "description": "Transaction information.", "properties": { "href": { "type": "string", "description": "Gift card resource URL. The number described in the URL refers to the gift card identification." } } } } }, "example": { "id": "38", "emissionDate": "2023-06-27T17:02:19.17", "expiringDate": "2023-09-27T17:02:19.17", "caption": "Loyalty Program", "provider": "GiftCardExample", "discount": false, "currencyCode":"USD", "transactions": { "href": "cosmetics2/giftcardproviders/GiftCardExample/giftcards/38/transactions" } } } } } } } }, "/api/giftcardproviders/{giftCardProviderId}/giftcards/_search": { "post": { "tags": [ "Transaction" ], "summary": "Get a gift card from a gift card provider", "description": "Returns all gift cards from a gift card provider according to the filters.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **View Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "GetGiftCardfromGiftCardProvider", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "REST-Range", "in": "header", "description": "Pagination control. This query variable must follow the format `_resources={from}-{to}_`.", "required": false, "style": "simple", "schema": { "type": "string", "default": "resources=0-49" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } } ], "requestBody": { "content": { "application/vnd.vtex.giftcardproviders.v1+json": { "schema": { "$ref": "#/components/schemas/GetGiftCardfromGiftCardProviderRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "Gift card information.", "properties": { "id": { "type": "string", "description": "Gift card identification." }, "provider": { "type": "string", "description": "Gift card provider name." }, "balance": { "type": "number", "description": "Gift card current balance." }, "_self": { "type": "object", "description": "Object that carries an auto reference from the provider at the Hub (on its API).", "properties": { "href": { "type": "string", "description": "This is one of the fields inside the `_self`. It is exactly the route that identifies this provider on the Hub's API, but it is not the same thing as the `serviceURL`." } } } } } }, "example": [ { "id": "262498", "provider": "GiftCardExample", "balance": 45.50, "_self": { "href": "cosmet/giftcardproviders/GiftCardExample/giftcards/262498" } } ] } } } } } }, "/api/giftcardproviders/{giftCardProviderId}/giftcards/{giftCardId}": { "get": { "tags": [ "Transaction" ], "summary": "Get a gift card from a gift card provider by ID", "description": "Returns a specific gift card from a gift card provider.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **View Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "GetGiftCardfromGiftCardProviderbyID", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "5" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Gift card identification." }, "redemptionToken": { "type": "string", "description": "Gift card redemption token." }, "redemptionCode": { "type": "string", "description": "Gift card identification code used at checkout. Minimum of 6 characters." }, "balance": { "type": "number", "description": "Gift card current balance. For newly created gift cards, the balance will be 0.0." }, "emissionDate": { "type": "string", "description": "Gift card emission date." }, "expiringDate": { "type": "string", "description": "Gift card expiration date." }, "currencyCode": { "type": "string", "description": "Currency code in ISO 4217." }, "discount": { "type": "boolean", "description": "Deprecated field.", "deprecated" : true }, "transactions": { "type": "object", "description": "Transactions information.", "properties": { "href": { "type": "string", "description": "This is one of the fields inside the `_self`. It is exactly the route that identifies this provider on the Hub's API, but it is not the same thing as the `serviceURL`." } } } } }, "example": { "id": "5", "redemptionToken": "32ScL57220Vapb8pc50HJ3mWH1cl1L8x", "redemptionCode": "***********ASDQ", "balance": 870.0, "emissionDate": "2014-04-24T20:22:58.163", "expiringDate": "2016-01-01T00:00:00", "currencyCode":"USD", "discount": false, "transactions": { "href": "cards/954/transactions" } } } } } } } }, "/api/giftcardproviders/{giftCardProviderId}/giftcards/{giftCardId}/transactions": { "get": { "tags": [ "Transaction" ], "summary": "List all gift card transactions", "description": "Returns the IDs of all transactions performed on a gift card.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **View Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "ListAllGiftCardTransactions", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "7d1dfc17-989e-4t21-8b7f-5103c6a5b925c_70" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "Transaction information.", "properties": { "cardId": { "type": "string", "description": "Gift card identification." }, "id": { "type": "string", "description": "Transaction identification." }, "_self": { "type": "object", "description": "Object that carries an auto reference from the provider at the Hub (on its API).", "properties": { "href": { "type": "string", "description": "This is one of the fields inside the `_self`. It is exactly the route that identifies this provider on the Hub's API, but it is not the same thing as the `serviceURL`." } } } } } }, "example": [ { "cardId": "7d1dfc17-989e-4t21-8b7f-5103c6a5b925c_70", "id": "jac68316306453f4b8tr3fdb892dfba1", "_self": { "href": "cosmetics2/giftcardproviders/GiftCardExample3/giftcards/7d1dfc17-989e-4t21-8b7f-5103c6a5b925c_70/transactions/jac68316306453f4b8tr3fdb892dfba1" } }, { "cardId": "7d1dfc17-989e-4t21-8b7f-5103c6a5b925c_70", "id": "g4a348e1d1f146ba25e19bb016cc6f18", "_self": { "href": "cosmetics2/giftcardproviders/GiftCardExample3/giftcards/7d1dfc17-989e-4t21-8b7f-5103c6a5b925c_70/transactions/g4a348e1d1f146ba25e19bb016cc6f18" } } ] } } } } }, "post": { "tags": [ "Transaction" ], "summary": "Create a gift card transaction", "description": "Creates a transaction (credit or debit) to a gift card.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Edit Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "CreateGiftCardTransaction", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "6" } } ], "requestBody": { "content": { "application/vnd.vtex.giftcardproviders.v1+json": { "schema": { "$ref": "#/components/schemas/CreateGiftCardTransactionRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "cardId": { "type": "string", "description": "Gift card identification." }, "id": { "type": "string", "description": "Transaction identification." }, "_self": { "type": "object", "description": "Object that carries an auto reference from the provider at the Hub (on its API).", "properties": { "href": { "type": "string", "description": "This is one of the fields inside the `_self`. It is exactly the route that identifies this provider on the Hub's API, but it is not the same thing as the `serviceURL`." } } } } }, "example": { "cardId": "24", "id": "68347b311ce5407c90fa5316975d047a", "_self": { "href": "gatewayqa/giftcards/24/transactions/68347b311ce5407c90fa5316975d047a" } } } } } } } }, "/api/giftcardproviders/{giftCardProviderId}/giftcards/{giftCardId}/transactions/{transactionId}": { "get": { "tags": [ "Transaction" ], "summary": "Get a gift card transaction by ID", "description": "Returns a specific transaction from a gift card.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **View Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "GetGiftCardTransactionbyID", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "7d1dfc17-989e-4t21-8b7f-5103c6a5b925c_70" } }, { "name": "transactionId", "in": "path", "description": "Transaction identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "jac68316306453f4b8tr3fdb892dfba1" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "number", "description": "Transaction value." }, "description": { "type": "string", "description": "Transaction description." }, "date": { "type": "string", "description": "Date of the transaction in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format (`YYYY-MM-DDThh:mm:ss.fff`)." }, "requestId": { "type": "string", "description": "VTEX request identifier." }, "settlement": { "type": "object", "description": "Settlement transaction information.", "properties": { "href": { "type": "string", "description": "Gift card resource URL. The first number described in the URL refers to the gift card identification. The second number, refers to the transaction identification." } } }, "cancellation": { "type": "object", "description": "Cancellation transaction information.", "properties": { "href": { "type": "string", "description": "Gift card resource URL. The first number described in the URL refers to the gift card identification. The second number, refers to the transaction identification." } } }, "authorization": { "type": "object", "description": "Authorization transaction information.", "properties": { "href": { "type": "string", "description": "Gift card resource URL. The first number described in the URL refers to the gift card identification. The second number, refers to the transaction identification." } } }, "operation": { "type": "string", "description": "Operation information (`Credit` or `Debit`)." } } }, "example": { "value": 140.0, "description": "GiftCardHub", "date": "2023-06-02T18:24:49.252855Z", "requestId": "3", "settlement": { "href": "cosmetics2/giftcardproviders/GiftCardExample3/giftcards/7d1dfc17-989e-4t21-8b7f-5103c6a5b925c_70/transactions/jac68316306453f4b8tr3fdb892dfba1/settlements" }, "cancellation": { "href": "cosmetics2/giftcardproviders/GiftCardExample3/giftcards/7d1dfc17-989e-4t21-8b7f-5103c6a5b925c_70/transactions/jac68316306453f4b8tr3fdb892dfba1/cancellations" }, "authorization": { "href": "cosmetics2/giftcardproviders/GiftCardExample3/giftcards/7d1dfc17-989e-4t21-8b7f-5103c6a5b925c_70/transactions/jac68316306453f4b8tr3fdb892dfba1/authorization" }, "operation": "Credit" } } } } } } }, "/api/giftcardproviders/{giftCardProviderId}/giftcards/{giftCardId}/transactions/{tId}/authorization": { "get": { "tags": [ "Transaction" ], "summary": "Get a gift card transaction authorization", "description": "Returns information about a gift card transaction authorization. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **View Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "GetGiftCardAuthorizationTransaction", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "7d1dfc17-989e-4t21-8b7f-5103c6a5b925c_70" } }, { "name": "tId", "in": "path", "description": "Transaction ID generated by the provider. It is different from the `transactionId` generated by VTEX.", "required": true, "style": "simple", "schema": { "type": "string", "example": "jac68316306453f4b8tr3fdb892dfba1" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "oid", "value", "date" ], "type": "object", "properties": { "oid": { "type": "string", "description": "Operation identification." }, "value": { "type": "number", "description": "Value information." }, "date": { "type": "string", "description": "Date of the transaction in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format (`YYYY-MM-DDThh:mm:ss.fff`)." } } }, "example": { "oid": "faa6831230634c4b8fb897e02ba9c5a1", "value": 140.0, "date": "2023-06-02T18:24:49.252855Z" } } } } } } }, "/api/giftcardproviders/{giftCardProviderId}/giftcards/{giftCardId}/transactions/{tId}/settlements": { "get": { "tags": [ "Transaction" ], "summary": "List all gift card transactions settlements", "description": "Returns all transactions settlements for a specific gift card.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **View Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "ListAllGiftCardSettlementTransactions", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "7d1dfc17-989e-4t21-8b7f-5103c6a5b925c_70" } }, { "name": "tId", "in": "path", "description": "Transaction ID generated by the provider. It is different from the `transactionId` generated by VTEX.", "required": true, "style": "simple", "schema": { "type": "string", "example": "jac68316306453f4b8tr3fdb892dfba1" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "oid", "value", "date" ], "type": "array", "items": { "type": "object", "description": "Transaction information.", "properties": { "oid": { "type": "string", "description": "Operation identification." }, "value": { "type": "number", "description": "Value information." }, "date": { "type": "string", "description": "Date of the transaction in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format (`YYYY-MM-DDThh:mm:ss.fff`)." } } } }, "example": [ { "oid": "faa6831230634c4b8fb897e02ba9c5a1", "value": 15.0, "date": "2023-06-02T18:24:49.252855Z" }, { "oid": "hbar6832580652c4b8fb653f15ba9c5a7", "value": 40.0, "date": "2023-06-04T15:00:35.252855Z" } ] } } } } }, "post": { "tags": [ "Transaction" ], "summary": "Settle a gift card transaction", "description": "Creates a transaction settlement for a specific gift card.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Edit Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "CreateGiftCardSettlementTransaction", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "6" } }, { "name": "tId", "in": "path", "description": "Transaction ID generated by the provider. It is different from the `transactionId` generated by VTEX.", "required": true, "style": "simple", "schema": { "type": "string", "example": "b47690" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "value", "requestId" ], "properties": { "value": { "type": "number", "description": "Transaction value.", "example": 1.8 }, "requestId": { "type": "string", "description": "Request identification of the transaction.", "example": "12093812masoidj120398" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "required": [ "oid", "value", "date" ], "type": "object", "description": "Transaction information.", "properties": { "oid": { "type": "string", "description": "Operation identification." }, "value": { "type": "number", "description": "Value information." }, "date": { "type": "string", "description": "Date information." } } } }, "example": [ { "oid": "e122ebd4501a4b3b93640b7444ac425d", "value": 1.8, "date": "2019-03-18T14:42:32.1291783Z" } ] } } } } } }, "/api/giftcardproviders/{giftCardProviderId}/giftcards/{giftCardId}/transactions/{tId}/cancellations": { "get": { "tags": [ "Transaction" ], "summary": "List all gift card transactions cancellations", "description": "Returns all transactions cancelled for a specific gift card.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **View Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "ListAllGiftCardCancellationTransactions", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "7d1dfc17-989e-4t21-8b7f-5103c6a5b925c_70" } }, { "name": "tId", "in": "path", "description": "Transaction ID generated by the provider. It is different from the `transactionId` generated by VTEX.", "required": true, "style": "simple", "schema": { "type": "string", "example": "jac68316306453f4b8tr3fdb892dfba1" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "oid", "value", "date" ], "type": "array", "items": { "type": "object", "description": "Transaction information.", "properties": { "oid": { "type": "string", "description": "Operation identification." }, "value": { "type": "number", "description": "Value information." }, "date": { "type": "string", "description": "Date of the transaction in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format (`YYYY-MM-DDThh:mm:ss.fff`)." } } } }, "example": [ { "oid": "1248f9b9d4564792b64013bba27151f2", "value": 30.0, "date": "2023-06-02T18:24:49.252855Z" }, { "oid": "8cb71c9e893A67E1b94d9b2ba15d102F", "value": 5.0, "date": "2023-06-08T11:30:00.252855Z" } ] } } } } }, "post": { "tags": [ "Transaction" ], "summary": "Cancel a gift card transaction", "description": "Creates a cancellation transaction to a gift card.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#application-keys) must have at least one of the appropriate [License Manager resources](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| GiftCard | GiftCard | **Edit Gift Card providers** |\r\n\r\nThere are no applicable [predefined roles](https:\/\/help.vtex.com\/en\/tutorial\/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https:\/\/help.vtex.com\/en\/tutorial\/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "operationId": "CreateGiftCardCancellationTransaction", "parameters": [ { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, { "name": "giftCardProviderId", "in": "path", "description": "Gift card provider identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "GiftCardExample" } }, { "name": "giftCardId", "in": "path", "description": "Gift card identification.", "required": true, "style": "simple", "schema": { "type": "string", "example": "6" } }, { "name": "tId", "in": "path", "description": "Transaction ID generated by the provider. It is different from the `transactionId` generated by VTEX.", "required": true, "style": "simple", "schema": { "type": "string", "example": "b47690" } } ], "requestBody": { "content": { "application/vnd.vtex.giftcardproviders.v1+json": { "schema": { "$ref": "#/components/schemas/CreateGiftCardCancellationTransactionRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "oid", "value", "date" ], "type": "object", "properties": { "oid": { "type": "string", "description": "Operation identification." }, "value": { "type": "number", "description": "Value information." }, "date": { "type": "string", "description": "Date of the transaction in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format (`YYYY-MM-DDThh:mm:ss.fff`)." } } }, "example": { "oid": "7582d93baccc44e9867b0b861696fc0a", "value": 4.1, "date": "2019-03-19T14:35:16.7157238Z" } } } } } } } }, "components": { "schemas": { "CreateUpdateGiftCardProviderbyIDRequest": { "required": [ "serviceUrl", "oauthProvider", "preAuthEnabled", "cancelEnabled", "appKey", "appToken" ], "type": "object", "description": "Gift card provider information.", "properties": { "id": { "type": "string", "description": "Gift card provider identification. This value must be the same as the one sent in the path parameter (`giftCardProviderId`).", "example": "customProvider" }, "serviceUrl": { "type": "string", "description": "URL from the provider.", "example": "https://api.vtex.com.br/example" }, "oauthProvider": { "type": "string", "description": "Provider's authentication.", "example": "vtex" }, "preAuthEnabled": { "type": "boolean", "description": "Related to the pre-authorization that can happen on the transaction generated through the provider.", "example": true }, "cancelEnabled": { "type": "boolean", "description": "Indicates whether it is possible to cancel the transaction, generated through the provider.", "example": true }, "appKey": { "type": "string", "description": "Credential provided by the merchant that VTEX will use for identification.", "example": "key" }, "appToken": { "type": "string", "description": "Credential provided by the merchant that VTEX will use for identification.", "example": "token" } } }, "CreateGiftCardinGiftCardProviderRequest": { "required": [ "relationName", "emissionDate", "expiringDate", "caption", "restrictedToOwner", "multipleRedemptions", "multipleCredits", "profileId" ], "type": "object", "description": "Gift card provider information.", "properties": { "relationName": { "type": "string", "description": "Represents the relationship between the client and the store.", "example": "loyalty-program" }, "emissionDate": { "type": "string", "description": "Gift card emission date. It must be in the format `YYYY-MM-DDThh:mm:ss.fff` (ISO 8601 format).", "example": "2020-09-01T13:15:30Z" }, "expiringDate": { "type": "string", "description": "Gift card expiration date. It must be in the format `YYYY-MM-DDThh:mm:ss.fff` (ISO 8601 format).", "example": "2020-09-10T13:15:30Z" }, "caption": { "type": "string", "description": "Field to be filled in if a loyalty program must be created for the gift card.", "example": "Loyalty Program" }, "restrictedToOwner": { "type": "boolean", "description": "The gift card can only be used for a specified client's ID.", "example": false }, "multipleRedemptions": { "type": "boolean", "description": "The gift card can be used to make new purchases until its value is completely used.", "example": false }, "multipleCredits": { "type": "boolean", "description": "The gift card balance can be changed.", "example": false }, "profileId": { "type": "string", "description": "Client ID. You can use the customer's registered email or the `userId` parameter which can be found in the [Master Data](https://help.vtex.com/en/tutorial/master-data--4otjBnR27u4WUIciQsmkAw).", "example": "92de2449-0e02-4ca9-a4aa-a09cc9d8f7ff" }, "currencyCode": { "type": "string", "description": "Currency code in ISO 4217.", "example": "USD" } } }, "GetGiftCardfromGiftCardProviderRequest": { "required": [ "client", "cart" ], "type": "object", "description": "Gift card provider information.", "properties": { "client": { "$ref": "#/components/schemas/Client" }, "cart": { "$ref": "#/components/schemas/Cart" } } }, "Client": { "type": "object", "description": "Client information.", "properties": { "id": { "type": "string", "description": "Customer's identification.", "example": "3b1abc17-988e-4a14-8b7f-31fc6a5b955c" }, "email": { "type": "string", "description": "Customer's email address.", "example": "email@domain.com" }, "document": { "type": "string", "description": "Document number informed by the customer.", "example": "42151783120" } } }, "Cart": { "type": "object", "description": "Cart information.", "properties": { "grandTotal": { "type": "integer", "description": "Total payment value.", "example": 0 }, "relationName": { "type": "string", "description": "Represents the relationship between the client and the store.", "example": "loyalty-program" }, "redemptionCode": { "type": "string", "description": "Gift card identification code used at checkout. Minimum of 6 characters.", "example": "***********ASDQ" }, "discounts": { "type": "integer", "description": "Discounts value.", "example": 20 }, "shipping": { "type": "integer", "description": "Shipping value.", "example": 2 }, "taxes": { "type": "integer", "description": "Taxes value.", "example": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item" }, "description": "Items information." }, "itemsTotal": { "type": "integer", "description": "Total items value.", "example": 200 } } }, "Item": { "type": "object", "description": "Items information.", "properties": { "productId": { "type": "string", "description": "Product ID.", "example": "2000000" }, "id": { "type": "string", "description": "The ID of the SKU in VTEX platform.", "example": "2000002" }, "refId": { "type": "string", "description": "Product Reference ID.", "example": "MEV41" }, "name": { "type": "string", "description": "Product name.", "example": "Shoes" }, "price": { "type": "integer", "description": "Product price.", "example": 200 }, "quantity": { "type": "integer", "description": "Product quantity.", "example": 1 } } }, "CreateGiftCardTransactionRequest": { "required": [ "operation", "value", "description", "redemptionToken", "redemptionCode", "requestId", "orderInfo" ], "type": "object", "description": "Transaction information.", "properties": { "operation": { "type": "string", "description": "Type of operation. Possible values are: `Debit` or `Credit`.", "example": "Debit" }, "value": { "type": "number", "format": "decimal", "description": "Operation value.", "example": 3 }, "description": { "type": "string", "description": "Description information.", "example": "GiftCardHub" }, "redemptionToken": { "type": "string", "description": "Gift card redemption token.", "example": "b2dac6f2-f365-48cd-82a9-0b376a55557a" }, "redemptionCode": { "type": "string", "description": "Gift card identification code used at checkout. Minimum of 6 characters.", "example": "***********ASDQ" }, "requestId": { "type": "string", "description": "Request identification of the transaction. You need to send a different `requestId` value every time you make a new transaction. If you send the same `requestId`two or more times with a specific `redemptionCode`or `redemptionToken`, the gift card balance will not be updated.", "example": "B56CBE231DEE4E1A859183C1030CE926" }, "orderInfo": { "$ref": "#/components/schemas/OrderInfo" } } }, "OrderInfo": { "type": "object", "description": "Order information.", "properties": { "orderId": { "type": "string", "description": "Order ID.", "example": "v5006128str" }, "sequence": { "type": "integer", "description": "Sequence number.", "example": 5006128 }, "cart": { "$ref": "#/components/schemas/Cart1" }, "clientProfile": { "$ref": "#/components/schemas/ClientProfile" }, "shipping": { "$ref": "#/components/schemas/Shipping" } } }, "Cart1": { "type": "object", "description": "Cart information.", "required": [ "items", "grandTotal", "discounts", "shipping", "taxes", "itemsTotal" ], "properties": { "items": { "type": "array", "description": "Items information.", "items": { "$ref": "#/components/schemas/Item1" } }, "grandTotal": { "type": "integer", "description": "Total payment value.", "example": 0 }, "discounts": { "type": "number", "description": "Discounts value.", "example":-7.5 }, "shipping": { "type": "number", "description": "Shipping value.", "example": 7.27 }, "taxes": { "type": "integer", "description": "Taxes value.", "example": 0 }, "itemsTotal": { "type": "number", "description": "Total items value.", "example": 14.99 } } }, "Item1": { "type": "object", "description": "Items information.", "required": [ "id", "productId", "refId", "name", "value", "price", "quantity", "shippingDiscount", "discount", "priceTags" ], "properties": { "id": { "type": "string", "description": "SKU ID.", "example": "2001023" }, "productId": { "type": "string", "description": "Product ID.", "example": "2000492" }, "refId": { "type": "string", "description": "Product Reference ID.", "example": "35994" }, "name": { "type": "string", "description": "Product name.", "example": "Vaporizador Des. ColC4nia Branco" }, "value": { "type": "number", "description": "Product value.", "example": 14.99 }, "price": { "type": "number", "description": "Product price.", "example": 14.99 }, "quantity": { "type": "integer", "description": "Product quantity.", "example": 1 }, "shippingDiscount": { "type": "integer", "description": "Discount to be applied for the shipping value.", "example": 0 }, "discount": { "type": "number", "description": "Discount applied on item.", "example": -7.5 }, "priceTags": { "type": "object", "description": "Array of price tags, each of which modifies the price in some way, like discounts or rates that apply to the item in the context of the order.", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "Price tag name.", "example": "discount@price-discount_store_183#4911bf6f-22a2-4af1-a365-cce895c3df2c" }, "value": { "type": "integer", "description": "Price tag value.", "example": 0 } } } } }, "ClientProfile": { "type": "object", "description": "Client profile information.", "required": [ "email", "firstName", "lastName", "document", "phone", "birthDate", "isCorporate" ], "properties": { "email": { "type": "string", "description": "Customer's email address.", "example": "michael.scott96@mail.com" }, "firstName": { "type": "string", "description": "Customer's first name.", "example": "Michael" }, "lastName": { "type": "string", "description": "Customer's last name.", "example": "Scott" }, "document": { "type": "string", "description": "Document number informed by the customer.", "example": "02906792063" }, "phone": { "type": "string", "description": "Customer's phone number.", "example": "+551111111111" }, "birthDate": { "type": "string", "description": "Customer's birth date.", "example": "0001-01-01T00:00:00" }, "isCorporate": { "type": "boolean", "description": "Defines if the customer is a company (`true`) or not (`false`).", "example": false } } }, "Shipping": { "type": "object", "description": "Shipping information.", "required": [ "receiverName", "postalCode", "city", "state", "country", "street", "number", "neighborhood", "complement", "reference" ], "properties": { "receiverName": { "type": "string", "description": "Name of the person who is going to receive the order.", "example": "Michael Scott" }, "postalCode": { "type": "string", "description": "Postal code.", "example": "22250040" }, "city": { "type": "string", "description": "City of the shipping address.", "example": "Rio de Janeiro" }, "state": { "type": "string", "description": "State of the shipping address.", "example": "RJ" }, "country": { "type": "string", "description": "Country of the shipping address.", "example": "BRA" }, "street": { "type": "string", "description": "Street of the shipping address.", "example": "Praia de Botafogo" }, "number": { "type": "string", "description": "Number of the building, house or apartment in the shipping address.", "example": "111" }, "neighborhood": { "type": "string", "description": "Neighborhood of the address.", "example": "Botafogo" }, "complement": { "type": "string", "description": "Complement to the shipping address in case it applies.", "example": "House", "nullable": true }, "reference": { "type": "string", "description": "Complement that might help locate the shipping address more precisely in case of delivery.", "example": "Subway", "nullable": true } } }, "CreateGiftCardSettlementTransactionRequest": { "type": "object", "description": "Gift card provider information.", "required": [ "client", "cart" ], "properties": { "client": { "$ref": "#/components/schemas/Client" }, "cart": { "$ref": "#/components/schemas/Cart2" } } }, "Cart2": { "type": "object", "description": "Cart information.", "required": [ "grandTotal", "relationName", "redemptionCode", "discounts", "shipping", "taxes", "items", "itemsTotal" ], "properties": { "grandTotal": { "type": "integer", "description": "Total payment value.", "example": 182 }, "relationName": { "type": "string", "nullable": true, "description": "Represents the relationship between the client and the store.", "example": null }, "redemptionCode": { "type": "string", "description": "Gift card identification code used at checkout. Minimum of 6 characters.", "example": "FASD-ASDS-ASDA-ASDA" }, "discounts": { "type": "integer", "description": "Discounts value.", "example": -20 }, "shipping": { "type": "integer", "description": "Shipping value.", "example": 2 }, "taxes": { "type": "integer", "description": "Taxes value.", "example": 0 }, "items": { "type": "array", "description": "Items information.", "items": { "$ref": "#/components/schemas/Item" } }, "itemsTotal": { "type": "integer", "description": "Total items value.", "example": 200 } } }, "CreateGiftCardCancellationTransactionRequest": { "type": "object", "description": "Transaction information.", "required": [ "value", "requestId" ], "properties": { "value": { "type": "number", "description": "Transaction value.", "example": 4.1 }, "requestId": { "type": "string", "description": "Request identification of the transaction.", "example": "12093812masoidj120398" } } } }, "securitySchemes": { "appKey": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppKey", "description": "Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys)." }, "appToken": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppToken", "description": "Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys)." }, "VtexIdclientAutCookie": { "type": "apiKey", "in": "header", "name": "VtexIdclientAutCookie", "description": "[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours." } } }, "tags": [ { "name": "Provider" }, { "name": "Transaction" } ], "security": [ { "appKey": [], "appToken": [] }, { "VtexIdclientAutCookie": [] } ] }